Add MkDocs Material documentation site with per-platform webhook guides and GitHub Pages deployment by Copilot · Pull Request #23 · cvraut/whecho

Copilot · 2026-03-09T17:31:56Z

whecho had no structured documentation beyond a README, making it hard to discover and difficult to onboard across platforms other than Discord.

Documentation structure (`docs/`)

index.md — Home page: what is whecho, quickstart (init → send), CLI reference, supported platforms table, TOC
api.md — whecho_simple reference: signature, parameters, return values, exceptions, platform auto-detection table, config file locations per OS
platforms/discord.md — Discord webhook creation walkthrough
platforms/slack.md — Slack App + Incoming Webhooks setup walkthrough
platforms/webex.md — Webex App Hub webhook setup; calls out Markdown support via the markdown payload field
platforms/teams.md — Teams Incoming Webhook connector setup, including note on new Teams app navigation differences

Config (`mkdocs.yml`)

Material theme with dark/light toggle, navigation.tabs, navigation.sections, content.code.copy, and pymdownx extensions for admonitions and fenced code.

CI (`/.github/workflows/docs.yml`)

Builds with mkdocs build --strict and deploys to GitHub Pages via actions/upload-pages-artifact + actions/deploy-pages on push to main. Pins mkdocs<2 to avoid the breaking MkDocs 2.0 release (incompatible with Material theme).

One-time setup required: enable GitHub Pages in repo Settings → Pages → Source: GitHub Actions.

Original prompt

This section details on the original issue you should resolve

<issue_title>Start a FAQ or documentation page detailing more supported use cases</issue_title>
<issue_description>I want more detailed setup instructions across other messaging platforms. Currently the documentation only shows how to use whecho with discord.

Either start a documentation page using sphinx, pandocs, docusaurus, etc... that contains more nuanced use cases and setup details

currently progress is being made to support slack as well. Perhaps integrate the slack webhook tutorial too

https://api.slack.com/messaging/webhooks
</issue_description>

<agent_instructions>Use the Material Theme with Mkdocs to start a basic documentation page for whecho. The documentation should include:

a basic home page detailing what is whecho and including a quickstart section with a detailed table of contents at the bottom.

a page about the public python api

detailed pages on how to obtain webhook links and integrate with different messaging clients

discord

slack

webex

teams

The documentation should be hosted on github within this project so also include a seperate yaml file in workflows to build and upload the documentation.</agent_instructions>

Comments on the Issue (you are @copilot in this section)
@cvraut seems like we can use github pages for hosting and deployment of the project. This can also aid in better SEO for whecho, currently very hard to google :(
This comment seems to have pretty detailed instructions for the SEO part: https://github.com/orgs/community/discussions/42375#discussioncomment-5296219 might be worth following once we get the pages & documentation up</comment_new>

Fixes Start a FAQ or documentation page detailing more supported use cases #8

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

…es deployment workflow Co-authored-by: cvraut <10603882+cvraut@users.noreply.github.com>

cvraut · 2026-03-09T18:11:34Z

I was unaware than mkdocs1.0 has been sunsetted... can you redo the documentation to use zensical instead?

Copilot

Pull request overview

Adds a MkDocs Material documentation site for whecho, with platform-specific webhook setup guides and a GitHub Actions workflow to deploy the site to GitHub Pages.

Changes:

Introduces MkDocs Material configuration (mkdocs.yml) with navigation + markdown extensions.
Adds documentation pages for the Python API and platform webhook setup (Discord/Slack/Webex/Teams).
Adds a GitHub Actions workflow to build and deploy docs to GitHub Pages.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
mkdocs.yml	Configures MkDocs Material theme, nav, and markdown extensions for the new docs site.
docs/index.md	Adds a home/quickstart page, CLI reference, supported platforms list, and TOC.
docs/api.md	Documents the public `whecho_simple` API and configuration details.
docs/platforms/discord.md	Adds a Discord webhook acquisition + usage walkthrough.
docs/platforms/slack.md	Adds a Slack Incoming Webhooks walkthrough.
docs/platforms/webex.md	Adds a Webex Incoming Webhooks walkthrough with payload details.
docs/platforms/teams.md	Adds a Microsoft Teams Incoming Webhooks walkthrough.
.github/workflows/docs.yml	Builds docs on `main` and deploys them to GitHub Pages.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Copilot · 2026-03-09T18:11:52Z

+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - attr_list
+  - md_in_html


Several docs pages use Markdown tables, but the tables extension isn’t enabled. MkDocs (Python-Markdown) doesn’t render tables unless tables is configured, so the tables in docs/index.md and docs/api.md will likely render as plain text. Add the tables markdown extension in mkdocs.yml.

Suggested change

- md_in_html

- md_in_html

- tables

Copilot · 2026-03-09T18:11:52Z

+| Platform | Guide |
+|---|---|
+| Discord | [Discord Webhook Setup](platforms/discord.md) |
+| Slack | [Slack Webhook Setup](platforms/slack.md) |
+| Webex | [Webex Webhook Setup](platforms/webex.md) |
+| Microsoft Teams | [Teams Webhook Setup](platforms/teams.md) |


The table syntax has an extra leading | on each row (|| ...), which creates an unintended empty first column (or can break rendering depending on the Markdown parser). Use standard table rows with a single leading pipe (| Platform | Guide |, etc.) here (and similarly in docs/api.md).

Copilot · 2026-03-09T18:11:52Z

+- `**bold**` or `*bold*`
+- `_italic_`


*bold* is typically italic in Markdown, not bold. This bullet should describe bold as **bold** (or __bold__) and reserve single-asterisk (or single-underscore) examples for italic.

Suggested change

- `**bold**` or `*bold*`

- `_italic_`

- `**bold**` or `__bold__`

- `*italic*` or `_italic_`

Copilot · 2026-03-09T18:11:53Z

@@ -0,0 +1,53 @@
+site_name: whecho
+site_description: Linux echo with webhooks!
+site_url: https://cvraut.github.io/whecho


For GitHub Pages sites served from a project subpath, it’s generally better to set site_url with a trailing slash (.../whecho/) to avoid canonical/SEO and relative URL edge cases. Consider updating site_url accordingly.

Suggested change

site_url: https://cvraut.github.io/whecho

site_url: https://cvraut.github.io/whecho/

Copilot · 2026-03-09T18:11:53Z

+          python-version: '3.11'
+
+      - name: Install MkDocs and Material theme
+        run: pip install "mkdocs-material" "mkdocs<2"


The workflow pins MkDocs but leaves mkdocs-material unpinned, which can introduce breakages from upstream theme releases. Consider pinning mkdocs-material to a known-good version range (or using a docs/requirements.txt / requirements-docs.txt with both pinned) and installing from that to make builds reproducible.

Suggested change

run: pip install "mkdocs-material" "mkdocs<2"

run: pip install "mkdocs-material>=9.5,<10" "mkdocs<2"

cvraut · 2026-03-09T19:35:23Z

closing PR as work is continuing in #24 instead

Initial plan

fec49b4

Copilot AI assigned Copilot and cvraut Mar 9, 2026

Copilot started work on behalf of cvraut March 9, 2026 17:32 View session

Add MkDocs Material documentation with platform guides and GitHub Pag…

d34aa0b

…es deployment workflow Co-authored-by: cvraut <10603882+cvraut@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add documentation page for supported use cases~~ Add MkDocs Material documentation site with per-platform webhook guides and GitHub Pages deployment Mar 9, 2026

Copilot finished work on behalf of cvraut March 9, 2026 17:38

cvraut requested a review from Copilot March 9, 2026 18:09

Copilot started reviewing on behalf of cvraut March 9, 2026 18:10 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

Copilot AI mentioned this pull request Mar 9, 2026

Switch documentation toolchain from MkDocs 1.x to Zensical #24

Open

cvraut closed this Mar 9, 2026

Navigation Menu

Add MkDocs Material documentation site with per-platform webhook guides and GitHub Pages deployment - #23

Add MkDocs Material documentation site with per-platform webhook guides and GitHub Pages deployment#23
cvraut with Copilot wants to merge 2 commits into
documentation_updatesfrom
copilot/start-documentation-page

Copilot AI commented Mar 9, 2026 •

edited

Loading

Uh oh!

cvraut commented Mar 9, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

Copilot AI Mar 9, 2026

Uh oh!

cvraut commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	site_url: https://cvraut.github.io/whecho
	site_url: https://cvraut.github.io/whecho/

	run: pip install "mkdocs-material" "mkdocs<2"
	run: pip install "mkdocs-material>=9.5,<10" "mkdocs<2"

Conversation

Copilot AI commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation structure (docs/)

Config (mkdocs.yml)

CI (/.github/workflows/docs.yml)

Comments on the Issue (you are @copilot in this section)

Uh oh!

cvraut commented Mar 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

cvraut commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 9, 2026 •

edited

Loading

Documentation structure (`docs/`)

Config (`mkdocs.yml`)

CI (`/.github/workflows/docs.yml`)